home *** CD-ROM | disk | FTP | other *** search
/ Aminet 4 / Aminet 4 - November 1994.iso / aminet / comm / net / netser100.lha / doc / netser.doc next >
Text File  |  1994-09-19  |  18KB  |  486 lines
  1. Document netser.doc
  2.  
  3.      =========================================================
  4.      netser V1.00 -- Virtual Serial Device Driver for Networks
  5.                          Documentation
  6.                      - September 18, 1994 -
  7.      =========================================================
  8.  
  9.        Copyright (c) 1994 by Sam Yee.  All rights reserved.
  10.  
  11.  
  12. 1. Legal Stuff
  13. ==============
  14.  
  15. 1.1. Copyright
  16. --------------
  17.  
  18. The   program,  netser  and  its  associated  files  are  written  and
  19. copyrighted  by  Sam  Yee.   netser  is SHAREWARE and the UNREGISTERED
  20. version  of  netser  may be distributed freely providing the following
  21. restrictions are satisfied:
  22.  
  23. o Distributors may not charge more than the cost of a diskette used in
  24.   the distribution of this program.
  25.  
  26. o Distributors may only distribute the unmodified copy of the original
  27.   program, along with its documentation, and copyright notices intact.
  28.  
  29. o Commercial  distribution  is  only  possible with written permission
  30.   from the author.
  31.  
  32. 1.2. License Agreement
  33. ----------------------
  34.  
  35. The   REGISTERED   versions   of  netser  may  not  be  redistributed.
  36. Redistribution  is  illegal,  immoral,  and  strictly prohibited.  The
  37. licensed keyfile may be used on more than one machine if you own those
  38. machines and that they are not for business use.  Otherwise, different
  39. keyfiles are required for each machine.
  40.  
  41. 1.3. Disclaimer
  42. ---------------
  43.  
  44. This   program  and  its  documentation  are  provided  "as  is".   No
  45. warranties  are  made  with  respect  to  the  accuracy,  reliability,
  46. performance  or  operation  of this software and information.  You are
  47. using this program at your own risk.  The author is not liable for any
  48. damages that may have been caused by using this software.
  49.  
  50.  
  51. 2. Introduction
  52. ===============
  53.  
  54. netser is a virtual device driver for accessing remote serial ports as
  55. if  they  were  local.   Currently,  it  only supports TCP/IP with the
  56. AmiTCP  package.   Support  for  other  packages  are planned.  netser
  57. emulates  low-level  serial  device  commands  over the network.  As a
  58. result,  your telecommunication (or "comm") program does not know, nor
  59. does  it  care, where your serial port is really located.  As you will
  60. see,  netser  allows  you  to  do things that have never been possible
  61. before!
  62.  
  63. Suppose  you  are  running  a  two  machine  network at home through a
  64. parallel  port  or  Ethernet card.  Wouldn't it be nice if one machine
  65. could  access  the  other machine's serial port?  You can conveniently
  66. call out to a BBS on any of the machines.  You may even run a two line
  67. BBS  without buying a multi-serial card!  And if you want to run a big
  68. BBS, but you don't have enough expansion slots to populate with serial
  69. cards.   What  you  can do is get another (slower) machine and connect
  70. the  two together with Ethernet.  netser will allow the BBS machine to
  71. use the other machine's ports.
  72.  
  73. With  netser  and  internet, you may run your favorite comm program on
  74. your  friend's  serial  port,  which may be half way across the world.
  75. This will save you long distance charges.
  76.  
  77. Now  that  Amiga  LAN's  exist, it would be convenient to dedicate one
  78. machine  on the LAN to hold modems that may be accessible to any other
  79. machine on the LAN.  (This is commonly known as a modem pool.) It is a
  80. common thing on Unix LAN's.  Your company will no longer have to drill
  81. holes in the walls to equip each machine with a modem.  As a matter of
  82. fact,  since  not everybody needs a modem all the time, the modems can
  83. be  shared.   Any  way  you put it, your company saves money.  Because
  84. most modems nowadays come with FAX capabilities , you can now fax from
  85. anywhere!
  86.  
  87. And  the  list of possibilities goes on and on.  The fact is, whatever
  88. you  do with the serial ports on your local machine, you can now do it
  89. with remote serial ports.  Only netser makes it possible!
  90.  
  91.  
  92. 3. Demo Restrictions
  93. ====================
  94.  
  95. All restrictions apply to the server side of netser.
  96.  
  97. The  demonstration version of netser allows connection time of 1 hour.
  98. When  the  time  expires,  your  comm  program  must  be  stopped  and
  99. restarted.   Furthermore, there is a limit of one device that could be
  100. opened by the server machine.
  101.  
  102. When  you  register  the  time limit will be eliminated.  Registration
  103. type  A  allows  2 devices, type B allows 4 devices, and type C allows
  104. unlimited devices.
  105.  
  106. To  register, please fill in the `Registration Form' and send it along
  107. with the fee to the address in section `Contact Address'.
  108.  
  109.  
  110. 4. Requirements
  111. ===============
  112.  
  113. netser  runs  on  any  Amiga(tm)  with version 2.04 of the OS, running
  114. AmiTCP.  It has been tested to work with AmiTCP 3.0, but may work with
  115. earlier versions.  netser uses very little memory (perhaps 50K).
  116.  
  117.  
  118. 5. Installation
  119. ===============
  120.  
  121. The netser archive contains the following files:
  122.  
  123. bin/netser          - client program used by devs/netser.device
  124. db/netser.imports   - device unit configuration for client
  125. db/netser.exports   - authorization file used by server
  126. devs/netser.device  - exec device driver to be opened by comm program
  127. serv/netserd        - server ("daemon") to be started by inetd
  128. doc/netser.doc      - documentation in text format
  129. doc/netser.guide    - documentation in AmigaGuide format
  130. s:netser.key        - registration keyfile for netser
  131.  
  132. To install netser, unpack the archive into AMITCP:.
  133.  
  134. For example:
  135.  1> lha x DH0:netser100.lha AMITCP:
  136.  
  137. Copy the device driver netser.device into devs:
  138.  
  139.  1> copy AMITCP:devs/netser.device devs: clone
  140.  
  141. Add the following line to AMITCP:db/inetd.conf:
  142.  
  143. netser    stream  tcp nowait root amitcp:serv/netserd
  144.  
  145. Add the following line to AMITCP:db/services:
  146.  
  147. netser          3000/tcp
  148.  
  149. The port 3000 is used for mere convenience.  (Since I have an A3000, I
  150. thought  it  would  be  a good number.) As long as it doesn't conflict
  151. with your other services, you can set it to anything you like.
  152.  
  153. If you are having problems installing, I'll be happy to help you.  See
  154. contact address at section `Contact Address'.
  155.  
  156.  
  157. 6. Configuration
  158. ================
  159.  
  160. netser.device     requires    two    configuration    files,    namely
  161. db/netser.imports,  and db/netser.exports.  In the files, a "#" or ";"
  162. forces  a line to be ignored.  db/netser.imports is used by the client
  163. machine, while db/netser.exports is used by the server machine.  Note,
  164. you should not use tabs in the config files to separate fields.
  165.  
  166. db/netser.imports has the following format:
  167.  
  168. # local  host[/port]     remote-device/unit  logfile
  169. # unit                   (wildcards OK)      ("" for none)
  170. # ----   ------------    ------------------  ---------------------
  171.   0      localhost       serial.device/0     "t:netser.log"
  172.   1      modempool       #?                  "t:netser.log"
  173.   3      123.45.67.89    oldser.device/0     "t:netser.log"
  174.   4      ""              serial.device/0     ""
  175.  
  176. Field  1  is  the local unit number used by netser.device to determine
  177. how  connections are made.  The number can be between 0 and 2 billion,
  178. but  bare  in  mind  that comm programs typically allow units 0 to 99.
  179. Field  2  specifies  the machine name (or IP address) where the remote
  180. serial  port  is to be found.  The service port number is optional and
  181. if none is given, the default is used.  Field 3 is the device and unit
  182. of that serial port.  It may contain AmigaDOS wildcards.  If wildcards
  183. are  used  all  remotely  defined  devices  are tried until one can be
  184. opened.   Finally,  field 4 is the file where you want all the logs to
  185. be  stored.  File names with spaces must be enclosed in double quotes.
  186. Log files are opened in append mode.  If you do not want logging, just
  187. enter "".
  188.  
  189. If  either  host[/port]  or  remote-device/unit is not given, a window
  190. will  be  opened  on  the  Workbench screen, allowing you to enter the
  191. missing  information.   Click  on Okay when you are done, or Cancel to
  192. force device open to fail.
  193.  
  194. As  a  suggestion, you should configure a unit to use a serial port on
  195. the  local  machine  ("localhost").   This  will  test  if all network
  196. communication run smoothly.
  197.  
  198. db/netser.exports has the following format:
  199.  
  200. #    local           IP address     allow/    Use      startup cleanup logfile
  201. # device/unit        or pattern     deny   OwnDevUnit? command command ("" for none)
  202. # -----------------  ----------     ------ ----------- ------- ------- --------------
  203.   serial.device/0    *.*.*.*        allow      Y         ""      ""   "t:netserd.log"
  204.   nullmodem.device/0 128.189.1.2    deny       N         ""      ""   ""
  205.  
  206. Field  1  defines  the  device  and  unit of the serial port you allow
  207. clients  to  use.   Field  2 and 3 control authorization to the serial
  208. port.   Field  2  is  the  IP  address of the machine to grant or deny
  209. access.   AmigaDOS  wildcards may be used.  Field 3 determines whether
  210. access  should  be  denied  or  granted.   When  field  4 is set to Y,
  211. OwnDevUnit.library  will  be  used  (if  available)  when  opening the
  212. device.   If don't already know, OwnDevUnit.library allows programs to
  213. use  the  serial  port  in  an orderly fashion.  Field 5 specifies the
  214. command  to  execute  prior  to  opening the device.  The command must
  215. return  a  result  code of 0 or else the device will not be attempted.
  216. The  sixth field is the command that will be executed after the device
  217. is  closed.   If you don't want any commands to be run, just enter "".
  218. Field  7 specifies the file to which all logs will be written.  Again,
  219. enter "" for none.
  220.  
  221. To  allow  more  than  one  machine  to  access  a serial port, simply
  222. duplicate the original line and change anything applicable, except for
  223. the device/unit.  For example:
  224.  
  225.  serial.device/0 1.2.3.4 allow Y "" "" "t:netserd.log"
  226.  serial.device/0 1.2.3.5 allow Y "" "" "t:netserd.log"
  227.  serial.device/0 1.2.3.6 deny  Y "" "" "t:netserd.log"
  228.  
  229. The  above allows hosts 1.2.3.4 and 1.2.3.5 to access serial.device/0,
  230. but not 1.2.3.6.
  231.  
  232.  
  233. 6.1. Modem Pool on a LAN
  234. ========================
  235.  
  236. On  every  machine in your LAN, the db/netser.imports file should look
  237. like:
  238.  
  239.  0   modempool   *   "t:netser.log"
  240.  
  241. And  on the machine that holds all the serial ports, db/netser.exports
  242. should look like:
  243.  
  244. serial.device/0 200.2.3.*   allow   Y   "" "" "t:netserd.log"
  245. serial.device/1 200.2.3.*   allow   Y   "" "" "t:netserd.log"
  246. serial.device/2 200.2.3.*   allow   Y   "" "" "t:netserd.log"
  247. serial.device/3 200.2.3.*   allow   Y   "" "" "t:netserd.log"
  248. ...
  249.  
  250. When  a client machine opens netser.device,0 all the serial devices in
  251. the  server  machine  (e.g.,  "modempool")  are attempted until one is
  252. opened  and quits if all of them are busy.  As you can see, only those
  253. machines in your domain are accessible to the serial ports.
  254.  
  255.  
  256. 7. How it works
  257. ===============
  258.  
  259. The following diagram depicts the communication between the client and
  260. remote machine.
  261.  
  262. <netser.device> <---> [netser] <-..-> [netserd] <---> [serial.device]
  263. (((((( LOCAL MACHINE ))))))))) (NET)  ((((((( REMOTE MACHINE ))))))))
  264.  
  265. [netser]   and  [netserd]  are  used  to  connect  <netser.device>  to
  266. <serial.device>.  [netser] is the client, and [netserd] is the server.
  267. A   custom  and  efficient  protocol  is  used  between  [netser]  and
  268. [netserd].
  269.  
  270. When  your comm program opens <netser.device> it launches [netser] and
  271. [netser] tries to connect to the remote machine.  When a connection is
  272. made,  inetd  launches [netserd].  [netserd] then checks authorization
  273. and opens the serial port.
  274.  
  275. When  you  quite  your comm program, [netser] tells [netserd] to close
  276. the  serial port.  [netserd] then exits and terminates the connection.
  277. Finally, netser.device closes.
  278.  
  279.  
  280. 8. Using netser.device
  281. ======================
  282.  
  283. To use netser.device, run your comm program the usual way.  Select the
  284. option   to   change   the   serial  device  and  unit.   Change  from
  285. "serial.device"   to   "netser.device".   Select  a  unit  defined  in
  286. db/netser.imports.   For  example,  if  you  use  the  definitions  in
  287. db/netser.imports  and  you  open  netser.device,3  you  are  actually
  288. opening oldser.device/0 at IP address 123.45.67.89.
  289.  
  290. If  the remote serial port is opened successfully, you should see some
  291. information  about netser on your terminal and which remote device you
  292. are using.  This is actually sent from the netser server on the remote
  293. machine.
  294.  
  295.  
  296. 9. Logging
  297. ==========
  298.  
  299. All  log  entries  have  a  time/date  stamp.  The log entry types are
  300. define as follows.
  301.  
  302. Client Log Messages
  303. -------------------
  304.  
  305. Trying <host>...
  306.     Client is trying to open connection with <host>
  307.  
  308. Closing remote device
  309.     Comm program is closing netser.device
  310.  
  311. select() error <code>
  312.     internal error <code> caused by select()
  313.  
  314. Opening <host>:<deviceunit> results in <resultcode>
  315.     Opening <deviceunit> at <host> results in <resultcode>
  316.  
  317. Connction closed by host (errno <code>)
  318.     netser server closed connection with client
  319.     error <code> is no error
  320.  
  321. Connection lost: quit comm prog now!
  322.     unable to receive bytes from the host
  323.  
  324. unknown host: <host>
  325.     <host> is not in your hosts file or your name server
  326.     try again with an IP address instead
  327.  
  328. tcp/netser: unknown service
  329.     the host does not have the netser service defined in the
  330.     serices file
  331.  
  332. socket() error
  333.     unable to open a socket
  334.  
  335. connect() error
  336.     unable to connect to host at a particular port number
  337.     check your host name and port number and try again
  338.     port number 0 is the default
  339.  
  340. Server Log Messages
  341. -------------------
  342.  
  343. Ping timeout
  344.     client is dead
  345.     server currently pings the client once every 5 minutes
  346.  
  347. select() error <code>
  348.     internal error <code> caused by select()
  349.  
  350. Connection from <IP-address> (port <port>)
  351.     A service request is made by <IP-address> at remote <port>
  352.  
  353. <deviceunit> already opened
  354.     an OpenDevice() call is made to <deviceunit> already
  355.  
  356. Opening <device>/<unit> results in <result>
  357.     reports the <result> of calling OpenDevice() on <device>/<unit>
  358.  
  359. bytes read: <read>; bytes written: <wrote>
  360.     i/o traffic
  361.  
  362. Connection closed by client (errno <code>)
  363.     client closed connection
  364.     errno <code> 0 is no error
  365.  
  366. Connection closed with client
  367.     we closed connection with client
  368.  
  369. <device>/<unit>: access denied
  370.     client is denied of <device>/<unit>
  371.  
  372. <device>/<unit>: access not declared
  373.     no access was granted for client to use <device>/<unit>
  374.  
  375.  
  376. 10. Performance and Compatibility
  377. =================================
  378.  
  379. When  sending  characters  using netser you may feel a delay in having
  380. what  you  typed  echo  back.   This  is to be expected because of the
  381. inefficiencies  in  sending  bytes at a time instead of blocks, over a
  382. network.   netser.device has been tested with ZModem file transfers on
  383. a  14.4kps  V.32BIS  modem.   It  was achieving rates of 1600cps using
  384. localhost.   On  the  same files, using serial.device directly, it was
  385. getting  about the same speed.  And on a LAN, it was getting 238cps on
  386. a  2400  baud  modem.   Therefore, it is safe to say that your network
  387. speed  determines the effective speed on using a remote modem.  I have
  388. not  tested  netser  on bi-directional protocols, but would appreciate
  389. any reports.
  390.  
  391. netser  is  very compatible with serial.device.  I can't say it's 100%
  392. because  I  can't prove it.  So far, I have tested it with NComm, VLT,
  393. and  Term  and it works fine.  All the official serial.device commands
  394. are  supported.   You  can  even  check if the remote modem has its CD
  395. light on.
  396.  
  397.  
  398. 11. Future Plans
  399. ================
  400.  
  401. Currently, I only have AmiTCP development documentation, so I can only
  402. write  and  test netser for this package.  When I get enough developer
  403. information  and resources, and if there is enough demand, I will port
  404. netser  to  other  network  packages  on the Amiga, such as AS225(tm),
  405. Envoy(tm),  Enlan(tm), and Parnet.  Ports on Unix(tm), Windows(tm) NT,
  406. and  OS/2(tm)  are  a  possibility.   It  would  be really nice to use
  407. PC/Unix-Workstation serial ports as Amiga serial ports!
  408.  
  409.  
  410. 12. Acknowledgements
  411. ====================
  412.  
  413. Thank-you's go to...
  414.  
  415.  - My co-workers at Taurus Ventures Inc. for beta-testing netser;
  416.  
  417.  - The AmiTCP group at Helsinki University for their great work;
  418.  
  419.  - Stephan Sürken for Text2Guide, which made creating AmigaGuide
  420.    documents easy; and
  421.  
  422.  - Marc Tooley (mtooley@sfu.ca) for beta-testing netser.
  423.  
  424.  
  425. 13. Registration Form
  426. =====================
  427.  
  428. ----------------------- netser Registration --------------------------
  429. Surname___________________________ Given Name_________________________
  430.  
  431. Company Name_________________ Type of Business________________________
  432.  
  433. Street Address________________________________________________________
  434.  
  435. City______________________________ Prov./State________________________
  436.  
  437. Country___________________________ Postal/ZipCode_____________________
  438.  
  439. E-Mail (please specify)_______________________________________________
  440.  
  441. ______________________________________________________________________
  442.  
  443. Can the above e-mail address accept uuencode files?___
  444.  
  445. Network software and hardware you are using?__________________________
  446.  
  447. ______________________________________________________________________
  448.  
  449. Where did you download netser?________________________________________
  450.  
  451. Version you have now__________________________________________________
  452.  
  453. Please mark with "*".  Version you are registering:
  454. [ ] A. 2 devices ..........$25US
  455. [ ] B. 4 devices ..........$35US
  456. [ ] C. unlimited devices ..$50US
  457.  
  458. Method of payment:
  459. [ ] Money order
  460. [ ] Personal cheque, please allow 3-4 weeks for clearance.
  461.     No personal cheques from outside of Canada.
  462. [ ] Cash.  Registered mail recommended.
  463.     I hold no responsibility for missing cash.
  464.  
  465. I have read the section `Legal Stuff' and agree with it.
  466.  
  467. _________________________  ___________________________________________
  468.        (Date)                           (Signature)
  469. ----------------------------------------------------------------------
  470.  
  471.  
  472. 14. Contact Address
  473. ===================
  474.  
  475. Registration  fees,  questions,  ideas,  comments,  bug  reports, etc.
  476. should go to:
  477.  
  478. Snail Mail: Sam Yee
  479.             4595 Nanaimo St.
  480.             Vancouver, B.C.
  481.             Canada  V5N 5J5
  482.  
  483.   Internet: samy@sfu.ca
  484.             sam_yee@res.com
  485.    FidoNet: 1:153/765 (Terra Firma BBS (604) 434-3665)
  486.